.\" Copyright (c) 2006-2020 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 29, 2006
.Dt AG_NOTEBOOK 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Notebook
.Nd agar notebook container widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(http://libagar.org/widgets/AG_Notebook.png, "A notebook with 3 tabs")
The
.Nm
widget maintains a set of
.Xr AG_Box 3
containers, only one of which is visible at any given time.
The user can select the visible container by clicking on a tab, or it can
be selected programmatically.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Notebook *"
.Fn AG_NotebookNew "AG_Widget *parent" "Uint flags"
.Pp
.Ft "void"
.Fn AG_NotebookSetPadding "AG_Notebook *nb" "int padding"
.Pp
.Ft "void"
.Fn AG_NotebookSetSpacing "AG_Notebook *nb" "int spacing"
.Pp
.Ft "void"
.Fn AG_NotebookSetTabAlignment "AG_Notebook *nb" "enum ag_notebook_tab_alignment alignment"
.Pp
.Ft "void"
.Fn AG_NotebookSetTabVisibility "AG_Notebook *nb" "int flag"
.Pp
.nr nS 0
The
.Fn AG_NotebookNew
function allocates, initializes, and attaches a new
.Nm
widget.
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_NOTEBOOK_HIDE_TABS "
.It AG_NOTEBOOK_HIDE_TABS
Don't display the tab selector controls.
.It AG_NOTEBOOK_HFILL
Expand horizontally in parent container.
.It AG_NOTEBOOK_VFILL
Expand vertically in parent container.
.It AG_NOTEBOOK_EXPAND
Shorthand for
.Dv AG_NOTEBOOK_HFILL | AG_NOTEBOOK_VFILL .
.El
.Pp
.Fn AG_NotebookSetPadding
and
.Fn AG_NotebookSetSpacing
sets the default
.Xr AG_Box 3
padding and spacing to use for new tabs.
.Pp
By default, tabs are drawn at the top of the widget.
.Fn AG_NotebookSetTabAlignment
changes the location of the tabs, where the argument is one of:
.Bd -literal
enum ag_notebook_tab_alignment {
	AG_NOTEBOOK_TABS_TOP,
	AG_NOTEBOOK_TABS_BOTTOM,
	AG_NOTEBOOK_TABS_LEFT,
	AG_NOTEBOOK_TABS_RIGHT
};
.Ed
.Pp
.Fn AG_NotebookSetTabVisibility
toggles the visibility of the tab header.
.Sh TAB MANAGEMENT
.nr nS 1
.Ft "AG_NotebookTab *"
.Fn AG_NotebookAdd "AG_Notebook *nb" "const char *name" "enum ag_box_type type"
.Pp
.Ft "void"
.Fn AG_NotebookDel "AG_Notebook *nb" "AG_NotebookTab *tab"
.Pp
.Ft "AG_NotebookTab *"
.Fn AG_NotebookGetByID "AG_Notebook *nb" "int tabID"
.Pp
.Ft "AG_NotebookTab *"
.Fn AG_NotebookGetByName "AG_Notebook *nb" "const char *text"
.Pp
.Ft "void"
.Fn AG_NotebookSelect "AG_Notebook *nb" "AG_NotebookTab *tab"
.Pp
.Ft "void"
.Fn AG_NotebookSelectByID "AG_Notebook *nb" "int id"
.Pp
.nr nS 0
.Fn AG_NotebookAdd
creates a new tabbed container.
.Fa name
is an arbitrary text label to be displayed on the tab header.
The
.Fa type
argument sets the type of
.Xr AG_Box 3 ,
that is either for
.Dv AG_BOX_HORIZ
horizontal packing, or
.Dv AG_BOX_VERT
for vertical packing (see
.Xr AG_Box 3
for details).
.Fn AG_NotebookAdd
returns a pointer to the newly created
.Ft AG_NotebookTab
container widget (a subclass of
.Xr AG_Box 3 ) .
.Pp
.Fn AG_NotebookDel
removes the given tabbed container, detaching and freeing all associated
child widgets.
.Pp
.Fn AG_NotebookGetByID
returns the tab with given numerical ID (or NULL).
.Pp
.Fn AG_NotebookGetByName
looks up a tab based on the contents of its text label and returns a pointer
to the tab (or NULL).
.Pp
The
.Fn AG_NotebookSelect
function selects the active tabbed container.
.Pp
.Fn AG_NotebookSelectByID
selects the container by numerical ID.
.Sh EVENTS
The
.Nm
widget does not generate any event.
.Sh STRUCTURE DATA
For the
.Ft AG_Notebook
object:
.Pp
.Bl -tag -width "AG_NotebookTab *selTab " -compact
.It Ft TAILQ tabs
The list of tabs as
.Ft AG_NotebookTab
objects.
.It Ft Uint nTabs
Total number of tabs.
.It Ft AG_NotebookTab *selTab
Pointer to the currently selected tab.
.It Ft int selTabID
Numerical ID of currently selected tab.
.El
.Pp
For the
.Ft AG_NotebookTab
object:
.Pp
.Bl -tag -width "AG_Label *lbl " -compact
.It Ft AG_Label *lbl
Pointer to the
.Xr AG_Label 3
of the tab (or NULL).
.It Ft int id
The numerical ID associated with the tab.
.El
.Sh EXAMPLES
The following code fragment creates a notebook with two tabs:
.Bd -literal -offset indent
AG_Notebook *nb;
AG_Notebook *ntab;

nb = AG_NotebookNew(parent, AG_NOTEBOOK_EXPAND);
{
	ntab = AG_NotebookAdd(nb, "Tab #1", AG_BOX_VERT);
	AG_LabelNew(ntab, 0, "This is Tab #1");

	ntab = AG_NotebookAdd(nb, "Tab #2", AG_BOX_VERT);
	AG_LabelNew(ntab, 0, "This is Tab #2");
}
.Ed
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.
.Fn AG_NotebookGetByID
and
.Fn AG_NotebookSelectByID
appeared in Agar 1.6.0.
